home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1997 April / EnigmA AMIGA RUN 17 (1997)(G.R. Edizioni)(IT)[!][issue 1997-04][EAR-CD].iso / EARCD / comm / misc / amigancp19.lha / AmigaNCP19 / Docs / AmigaNCP.doc next >
Text File  |  1996-11-13  |  59KB  |  1,887 lines
  1.  
  2.  
  3. AmigaNCP
  4. ********
  5.  
  6. Welcome to the AmigaNCP package, the AmigaOS implementation of
  7. Psion's NCP network protocol.
  8.  
  9. Copyright
  10. *********
  11.  
  12. The AmigaNCP package has been written by
  13.  
  14.      Oliver Wagner
  15.      Märkische Str. 24
  16.      D-42281 Wuppertal
  17.      Germany
  18.      
  19.      email: owagner@vapor.com
  20.  
  21. The AmigaNCP driver library, the AmigaNCP File Server, the AmigaNCP
  22. File System, the AmigaNCP Documentation and all associated files are
  23. copyright (C) 1993-1996 Oliver Wagner, All Rights Reserved.
  24.  
  25.     Psion, the Psion Logo, Psion Series 3, 3-Link, Psion HC,
  26. Psion MC, SSD and Solid State Disk are registered Trademarks of
  27. Psion PLC.
  28.  
  29. The author wishes to thank the following people for their help during
  30. AmigaNCP development:
  31.  
  32. David Wood of Psion Ltd.
  33.      Who provided the necessary information about the NCP protocol and
  34.      helped with beta testing the package
  35.  
  36. Jeremy "Jezar" Wakefield of Psion Ltd.
  37.      Who helped to track down several hidden and esoteric bugs.
  38.  
  39. Eric (ed@ramses.fdn.org)
  40.      For providing the french catalog translation.
  41.  
  42. Phil Trickett (phil@dcs.king.ac.uk)
  43.      For the additional icon images.
  44.  
  45. Introduction
  46. ************
  47.  
  48. Overview
  49. ========
  50.  
  51. Psion's fine palmtop computer series, namely the S3 and S3a,
  52. contain an even finer operating system, whose neat features cover a full
  53. fledged peer-to-peer networking software using a protocol called
  54. NCP.
  55.  
  56. Using NCP, you can link together two Psion computers or a Psion and a
  57. different, perhaps stationary machine and happily exchange data on your
  58. behalf.  NCP services include, but are not limited to, accessing files
  59. on the remote machines as if they were on yours, in both directions.
  60.  
  61. Linking your palmtop to your stationary machine is generally quite a
  62. good idea.  Doing so via the NCP protocol requires your stationary
  63. machine to have an implemention of this protocol.  There have only been
  64. implementations for MS-DOS clones (the MCLINK.EXE shell), for Apple
  65. MacIntosh and for Acorn Archimedes - until now.
  66.  
  67. AmigaNCP features a full NCP implementation including a remote file
  68. server to access Amiga files from your Psion and a file system to access
  69. Psion files from your Amiga.  The package also offers an API to allow
  70. custom applications to directly access network services at the NCP
  71. level.
  72.  
  73. Parts of AmigaNCP
  74. =================
  75.  
  76. AmigaNCP actually consists of several different programs.
  77.  
  78. The main part is the amigancp.library.  It contains the basic network
  79. services for exchanging data between two machines via a serial
  80. connection.  The protocol provides up to 8 data channels, which can be
  81. either passive (awaiting a connection from a client process) or active
  82. (attempting to connect to a server process).  One of the channels is
  83. reserved for the network supervisor application LINK.  The LINK
  84. functionality also has been integrated into amigancp.library.
  85.  
  86. Besides network I/O functions, the library also provides several
  87. utility functions to deal with Psion text format and the Intel byte
  88. ordering.
  89.  
  90. The AmigaNCP-FileServer is an application built on top of
  91. amigancp.library.  It provides a means of accessing AmigaDOS
  92. files from the remote Psion computer via the REM:: file system.  This
  93. allows you to access Amiga files just as if they were local Psion
  94. files.  With the Psion S3a, it allows you to use the Backup option to
  95. backup vital data files on your Amiga's harddisk.
  96.  
  97. The AmigaNCP-FileSystem uses the amigancp.library to connect to
  98. the file server running on your Psion in order to provide access to
  99. Psion files from the AmigaDOS environment.  It provides a new AmigaDOS
  100. device named NCP: which offers access to all available Psion devices.
  101. The Psion devices will be mounted as subdirectories in the NCP:
  102. window.
  103.  
  104. The AmigaNCP-Monitor monitors the activity of the NCP supervisor and
  105. gives detailed statistics about all channels.  This is an invaluable
  106. aid for debugging NCP applications.
  107.  
  108. The S3PrintServer allows you to print from your S3 or S3a directly to
  109. a printer connected to the Amiga.
  110.  
  111. The S3Run program remotely launches programs or applications on your
  112. Psion.
  113.  
  114. Using AmigaNCP
  115. **************
  116.  
  117. Installation
  118. ============
  119.  
  120. For using AmigaNCP you'll need...
  121.  
  122.   1. any Amiga equipped with OS 2.04 or better and a free serial port
  123.  
  124.   2. the IBM-PC version of the 3-Link serial cable
  125.  
  126.   3. and a Psion S3 or S3a (or any other model featuring Remote
  127.      Link)(1).
  128.  
  129.  
  130. To support Amiga systems without a hard disk, the AmigaNCP distribution
  131. has been organized to be ready-to-use.
  132.  
  133. Hard disk installation of AmigaNCP is best done using the provided
  134. Installer script.  The script will (by default) copy
  135. amigancp.library to LIBS:, put the language catalogs into
  136. LOCALE:Catalogs/ and create an AmigaNCP drawer on your work
  137. partition.  The drawer will contain the network services, documentation
  138. and the NCP tools.  There's an additional option for installing the
  139. amigancp.library developer material.
  140.  
  141. When installing the package for the first time, the installation
  142. procedure will ask you about the Psion model you're going to connect
  143. to.  The serial line speed will be set to the model's maximum (that is
  144. 9600 baud for the S3 or HC and 19200 baud for S3a or MC). You may
  145. change the serial parameters later on, though.
  146.  
  147. Configuring amigancp.library
  148. ============================
  149.  
  150. The default serial configuration is to use the serial.device, unit 0,
  151. at 9600 baud(2).
  152.  
  153. You can overwrite these default parameters by setting or changing the
  154. environment variable NCP.config.  The environment variable will be
  155. read by the amigancp.library each time a serial connection has to be
  156. established.
  157.  
  158. The parameter parsing is done just like in a shell command line; the
  159. template is D=DEVICE/K, U=UNIT/K/N, B=BAUD/K/N, NOREQ/S.  All
  160. parameters are optional, those not given will retain their default
  161. values.
  162.  
  163. An example:  To make AmigaNCP use duart.device, unit 1 at 19200 baud
  164. you have to set ENV:NCP.config to
  165.  
  166.     DEVICE=duart.device UNIT=1 BAUD=19200
  167.  
  168. The installation script will create both ENV:NCP.config and
  169. ENVARC:NCP.config with either
  170.  
  171.     DEVICE=serial.device UNIT=0 BAUD=9600
  172.  
  173. or
  174.  
  175.     DEVICE=serial.device UNIT=0 BAUD=19200
  176.  
  177. depending on your choice of Psion model.  Please note, that you may
  178. actually use any baud rate supported by the serial port in question
  179. (and of course supported by the other side's serial interface as well).
  180.  
  181. If you set the NOREQ switch, the library will not display any error
  182. requesters.
  183.  
  184. Note that you have to configure the remote site as well.  On the Psion
  185. S3 or S3a this consists of turning on NCP via the Remote Link menu of
  186. the system screen.  The baud rate must of course be set to the same
  187. value as used in ENV:NCP.config, or to 9600 if no configuration file
  188. exists.
  189.  
  190. Starting AmigaNCP
  191. =================
  192.  
  193. You don't start amigancp.library directly.  Instead you start one or
  194. more of the AmigaNCP applications, which in turn will open the library
  195. and try to establish their connections to the remote NCP site.
  196.  
  197. The library automatically terminates a connection about 10 seconds
  198. after the last application has closed its network channels.
  199.  
  200. Note that the underlying serial device is free to be used by any other
  201. application as long as no NCP connection is active and no connection
  202. attempt is made.
  203.  
  204. NCP Requesters
  205. ==============
  206.  
  207. The amigancp.library will put up error requesters if the network link
  208. breaks (and the NOREQ switch hasn't been set, see above).  The
  209. following table shows possible error conditions:
  210.  
  211. Can't open serial device
  212.      The device specified in ENV:NCP.config could not be opened.
  213.      Either the device does not exist (perhaps just because you
  214.      misspelled the device name) or it is in use by another process.
  215.  
  216. Timeout waiting for response
  217.      The serial device opened ok but the other side is not responding
  218.      to our handshake packet.  Most likey there is no Psion connected,
  219.      or it has it's Remote Link turned off.  This requester will
  220.      constantly show up if the AmigaNCP file system is running and the
  221.      serial link broke down.
  222.  
  223. Data not acknowledged
  224.      The last data packet has not been acknowledged.  This normally
  225.      denotes an NCP connection which has been interrupted during data
  226.      transfer.
  227.  
  228. Connection dropped
  229.      The remote side dropped the connection.
  230.  
  231. Argument error
  232.      Bad LLMAC request arguments.  You normally should not see this
  233.      error, it denotes an internal failure in the amigancp.library
  234.      high level I/O functions.
  235.  
  236. Not connected
  237.      There is no LLMAC connection.  You normally should not see this
  238.      error, it denotes an internal failure in the amigancp.library
  239.      high level I/O functions.
  240.  
  241. ---------- Footnotes ----------
  242.  
  243. (1)  In fact of course any NCP implementation does.  You can use
  244. AmigaNCP to connect to an NCP server running on an IBM PC or Apple Mac,
  245. or even to another AmigaNCP running on a different Amiga.
  246.  
  247. (2)  All other serial flags are fixed to 8N1, highspeed mode and 7-wire
  248. RTS/CTS handshake since this is required by the NCP protocol.
  249.  
  250. AmigaNCP File Server
  251. ********************
  252.  
  253. Introducing the File Server
  254. ===========================
  255.  
  256. The AmigaNCP File Server is an NCP application which provides access
  257. to Amiga files from the remote machine.  On startup it creates a
  258. passive NCP channel awaiting a connection from a remote file system.
  259.  
  260. On the S3 and S3a, the remote file system is built into the ROM.  It
  261. automatically attempts to connect to the remote file server when an NCP
  262. connection is made, and presents a new filesystem node named REM::,
  263. which in turn contains all the Amiga devices.  You can navigate through
  264. the Amiga devices via the system screen or directly access a file by
  265. it's full path name.
  266.  
  267. The Psion's file system was designed to be device independant, so there
  268. are no restrictions concerning the length of file names or extensions:
  269. The complete Amiga device, directory and file names are fully
  270. preserved.  However, directories are separated in the standard Psion
  271. manner via the \ character.
  272.  
  273. An example:  To access the Amiga file HD1:Test/Test.txt from the
  274. Psion, use the file name REM::HD1:\TEST\TEST.TXT.  To access
  275. SYS:S/Startup-Sequence, use REM::\SYS:\STARTUP-SEQUENCE.
  276.  
  277. When asked for a device list, the AmigaNCP File Server will output only
  278. real file system devices(1).  However, you may in fact access any
  279. AmigaDOS device, even volumes and assigned names, from the remote site
  280. by using the direct path to it.
  281.  
  282. An example:  To access the Amiga's parallel port from the remote site,
  283. just use the path REM::PAR:\.  This is quite useful for using the
  284. print-to-file capabilities of some of the Psion applications.
  285.  
  286. Character conversion mode
  287. =========================
  288.  
  289. Since the Psion's operating system uses a different character codeset
  290. than the Amiga does, you normally can't easily exchange ASCII files
  291. between the two machines.  The AmigaNCP File Server however provides a
  292. special conversion mode which allows to convert files on the fly.
  293.  
  294. Whenever you add the special extension .CV to any remote file name,
  295. all characters read from or written to that file will
  296. automatically be converted by AmigaNCP.  The conversion is fully
  297. transparent to your applications.
  298.  
  299. An example:  To edit the Amiga text file HD1:Test/Test.TXT on the S3
  300. with automatic character conversion, use the virtual file name
  301. REM::HD1:\TEST\TEST.TXT.CV.
  302.  
  303. Note that character conversion mode should be used only for text
  304. files.  The S3 and S3a Word file format for example contains binary
  305. data which will be gracefully mangled if accessed in conversion mode.
  306.  
  307. File Server Options
  308. ===================
  309.  
  310. The AmigaNCP File Server may be started either from the shell or from
  311. Workbench.  To terminate the server, just start it again, it will put
  312. up a requester showing you the number of files in use and asking you
  313. whether you really want to quit.
  314.  
  315. The File Server accepts several options to modify the way it operates.
  316. Note that you have to set up amigancp.library first (See Using
  317. AmigaNCP.).
  318.  
  319. Options may be given on the command line (shell) or using tooltype
  320. entries (Workbench).  You may use project icons to start the File
  321. Server in order to have different configurations at hand.
  322.  
  323. The option template is:
  324.          IBM=CHARSETCONV/S,
  325.      SHOWICONS=SHOWINFO/S,
  326.      HIDEEMPTYDRIVES/S,
  327.      BUFFER=BUFFERSIZE
  328. You may enter ? to get additional help at the command line.  Detailed
  329. parameter descriptions follow.
  330.  
  331. CharSetConv
  332. -----------
  333.  
  334. When the remote file system requests a directory scan, the file server
  335. examines each file to determine whether it is a text file or not(2).
  336. Text files are then returned both with their normal name and with the
  337. magic extension .CV added.
  338.  
  339. ShowInfo
  340. --------
  341.  
  342. Show *.info and .backdrop files during a directory scan.  You
  343. normally shouldn't set this option, the Psion has no use for these
  344. files and directory scans are much faster without them.
  345.  
  346. Please note that the Psion's Delete Whole Directory function will
  347. only work correctly on Amiga directories if ShowInfo has been enabled.
  348.  
  349. HideEmptyDrives
  350. ---------------
  351.  
  352. Upon a device list query, don't return drives which currently do not
  353. contain a medium.  This option is intended mainly to overcome an
  354. annoying quirk in the S3 and S3a system screen which resets the current
  355. device to LOC::\M\ each time a device reports E_NOT_READY.  This
  356. normally always happens when getting to REM::DF0: with no disk in the
  357. drive.
  358.  
  359. Note that, although these devices are not visible in the device list,
  360. they may as usual be accessed by manually entering the device name.
  361.  
  362. BufferSize
  363. ----------
  364.  
  365. Set the size of the filehandle buffers used by the File Server.  This
  366. parameter defaults to 4096 Bytes and normally doesn't need to be
  367. changed(3).
  368.  
  369. ---------- Footnotes ----------
  370.  
  371. (1)  Tech info:  Any device which responds positively to
  372. ACTION_IS_FILESYSTEM is considered to be a real file system.
  373.  
  374. (2)  Tech info:  This is done by reading the first 512 Bytes and
  375. scanning them for non-printable characters.  Files with the S
  376. protection bit set are always assumed to be text files.
  377.  
  378. (3)  This option has no effect on AmigaOS below version 3.1
  379.  
  380. AmigaNCP File System
  381. ********************
  382.  
  383. Introducing the File System
  384. ===========================
  385.  
  386. The AmigaNCP File System is an NCP application which provides access
  387. from the AmigaDOS environment to files on the remote machine.  It
  388. creates a new AmigaDOS device named NCP:, which in turn contains all
  389. remote devices as subdirectories.
  390.  
  391. The Amiga directory NCP:A refers to the device A: on the remote
  392. side, NCP:M refers to M: and so on.
  393.  
  394. If you want to access any file on the remote device, just add the full
  395. path name.  To access the file A:\WRD\SECRET.WRD, just use the Amiga
  396. file name NCP:A/WRD/SECRET.WRD.
  397.  
  398. You can access the new device from any Amiga application, including
  399. Workbench and your favourite directory tool, as if they were standard
  400. Amiga files.
  401.  
  402. On startup, the AmigaNCP File System immediately attempts to connect to
  403. the File Server on the remote machine.  If no connection can be made,
  404. the File System will refuse to start.  You may attempt to quit it at
  405. any time by starting it again, however, due to AmigaDOS constraints it
  406. will refuse to quit if there are any files or locks still in use.
  407.  
  408. Character Conversion Mode
  409. =========================
  410.  
  411. The AmigaNCP File System also features the character conversion mode.
  412. If you enable this option, all remote devices will be mirrored as
  413. CONV_<devname>, and all characters read from or written to files
  414. within these subdirectories will automatically be converted.
  415.  
  416. Example:  To access A:\WRD\SECRET.TXT with character conversion, use
  417. the file name NCP:CONV_A/WRD/SECRET.TXT.
  418.  
  419. The translation is fully transparent; you may, for example, use your
  420. favourite text editor to load a text file from the Psion, edit it and
  421. save it again.  Upon reading, it will be converted to the Amiga ISO
  422. character set, upon writing, it will be converted back to the IBM codes
  423. used by the Psion.
  424.  
  425. File System Options
  426. ===================
  427.  
  428. The File System accepts several options to modify the way it operates.
  429. Note that you have to set up amigancp.library first (See Using
  430. AmigaNCP.).
  431.  
  432. Upon shell startup, options are specified on the command line.  The
  433. template is:
  434.          VOL=VOLUMENAME/K,
  435.      DEV=DEVICENAME/K,
  436.      SR=SHAREDREAD/S,
  437.      IBM=CHARSETCONV/S,
  438.      HED=HIDEEMPTYDRIVES/S,
  439.      DWMS=DONTWARNMISSINGSERVER/S,
  440.      ARR=AUTOREREAD/S,
  441.      ID=ICONDIR/S
  442. You may enter ? to get additional help at the command line.  See
  443. below for detailed descriptions of these parameters.
  444.  
  445. If started from Workbench, the File System application will read its
  446. icon and parse the tooltypes for the same option keywords.  You may use
  447. project icons for starting the File System in order to have different
  448. configurations at hand.
  449.  
  450. VolumeName
  451. ----------
  452.  
  453. This options allows you to set the volume node name of the File System.
  454. Defaults to AmigaNCP-Remote.  This is the name the Workbench shows
  455. below the disk icon.
  456.  
  457. DeviceName
  458. ----------
  459.  
  460. Modifies the device name of the File System.  Defaults to NCP:.
  461.  
  462. SharedRead
  463. ----------
  464.  
  465. For historical reasons, there is no real read only mode in the
  466. AmigaDOS.  The access mode MODE_OLDFILE can be used for reading and
  467. writing an existing file from multiple accessors.  So an Amiga file
  468. system cannot predict whether a file opened with MODE_OLDFILE will
  469. also be written to.
  470.  
  471. The Psion filing system however limits multiple file access to read
  472. only mode.
  473.  
  474. To be as compatible as possible with existing Amiga applications, the
  475. AmigaNCP File System by default translates MODE_OLDFILE to exclusive
  476. read/write access on the Psion.
  477.  
  478. This may cause problems if a file is already opened for reading from
  479. the Psion side, perhaps because you have a Psion application running
  480. which accesses this file.  Even a read only access from the Amiga side
  481. will fail because it translates to a read/write access on the Psion
  482. side.
  483.  
  484. In order to overcome this AmigaDOS quirk, the AmigaNCP File System
  485. provides this option to translate MODE_OLDFILE to a shared read
  486. access on the Psion side.  Every write attempt on such a file will
  487. result in a ERROR_WRITE_PROTECTED.
  488.  
  489. CharSetConv
  490. -----------
  491.  
  492. Activate character conversion mode.  All Psion devices are mirrored as
  493. CONV_<devname and read/write accesses to files within these drawers
  494. are silently translated.
  495.  
  496. Note that file handles opened in character conversion mode don't
  497. support ACTION_SEEK.  This may cause problems with some applications.
  498.  
  499. HideEmptyDrives
  500. ---------------
  501.  
  502. Don't create subdirectories for Psion devices which don't contain a
  503. medium.
  504.  
  505. DontWarnMissingServer
  506. ---------------------
  507.  
  508. The File Server should normally be started first, because the Psion
  509. LINK application attempts to contact it as soon as the connection has
  510. been established, and it will not try again if no connection could be
  511. made.
  512.  
  513. Therefore, the File System will warn you with a requester if it can't
  514. detect the AmigaNCP File Server when it is started.  Setting this option
  515. instructs the File System not to do so.
  516.  
  517. AutoReRead
  518. ----------
  519.  
  520. By default, the File System reads the remote device list only once at
  521. the time it is started.
  522.  
  523. This should normally be no problem, unless you use HideEmptyDrives
  524. and replace SSD cartridges while a connection is active.
  525.  
  526. You can use DiskChange NCP: at any time to manually force the File
  527. System to read the device list again.  Or you can set AutoReRead,
  528. which causes the File System to read the device list from the remote
  529. side upon every access, which of course will slow accesses down a bit.
  530.  
  531. IconDir
  532. -------
  533.  
  534. In order to be compatible with the Workbench environment, the File
  535. System stores icon and workbench information files (.info and
  536. .backdrop) in a special file hierarchy on the AmigaDOS side.
  537. This allows you to do snapshoting and backdroping of icons belonging to
  538. Psion files without wasting valuable storage memory on the Psion.  This
  539. also avoids the problem that the Psion file system can't handle file
  540. extensions longer than three characters.
  541.  
  542. The default path for storing these files is the drawer Icons in the
  543. subdirectory where the File System program resides.  Using the
  544. IconDir option, you can specify another path.  This is quite
  545. useful if you use AmigaNCP to connect to different Psions with
  546. different file structures.
  547.  
  548. The file structure inside this IconDir drawer is organized exactly like
  549. in the NCP: device.  So, a icon file belonging to WRD drawer on the
  550. M device on the Psion is located in Icons/M/WRD.info.
  551.  
  552. Implementation Details
  553. ======================
  554.  
  555. The AmigaNCP File System supports the following AmigaDOS packet types:
  556.  
  557.    * ACTION_IS_FILESYSTEM
  558.  
  559.    * ACTION_FLUSH
  560.  
  561.    * ACTION_DISK_INFO
  562.      The resulting disk sizes are calculated by adding the per-device
  563.      sizes of the underlying Psion devices.
  564.  
  565.    * ACTION_INFO
  566.  
  567.    * ACTION_COPY_DIR
  568.  
  569.    * ACTION_COPY_DIR_FH
  570.  
  571.    * ACTION_LOCATE_OBJECT
  572.  
  573.    * ACTION_FREE_LOCK
  574.  
  575.    * ACTION_EXAMINE_FH
  576.  
  577.    * ACTION_EXAMINE_OBJECT
  578.  
  579.    * ACTION_EXAMINE_NEXT
  580.      Psion directory lists are read completly on the first EXNEXT
  581.      packet and kept in a private cache of the lock. This results in a
  582.      ExAll() like performance even with using the old style directory
  583.      scanning packets.
  584.  
  585.    * ACTION_CURRENT_VOLUME
  586.  
  587.    * ACTION_SAME_LOCK
  588.  
  589.    * ACTION_CREATE_DIR
  590.  
  591.    * ACTION_PARENT
  592.  
  593.    * ACTION_PARENT_FH
  594.  
  595.    * ACTION_DELETE_OBJECT
  596.  
  597.    * ACTION_RENAME_OBJECT
  598.      Note that renaming an non-icon file to an icon-file will yield
  599.      ERROR_RENAME_ACROSS_DEVICES.
  600.  
  601.    * ACTION_DIE
  602.  
  603.    * ACTION_FINDINPUT
  604.      See the description of the SharedRead option for differen
  605.      translation modes.
  606.  
  607.    * ACTION_FINDOUTPUT
  608.  
  609.    * ACTION_FINDUPDATE
  610.      This always translates to exclusive access on the Psion side.
  611.  
  612.    * ACTION_INHIBIT
  613.  
  614.    * ACTION_END
  615.  
  616.    * ACTION_READ
  617.  
  618.    * ACTION_WRITE
  619.  
  620.    * ACTION_SEEK
  621.      Not available on files opened in character conversion mode.
  622.  
  623.    * ACTION_SET_PROTECT
  624.      Supports FIBF__ARCHIVE, FIBF_READ, FIBF_WRITE  and
  625.      FIBF_EXECUTE.
  626.  
  627.    * ACTION_SET_DATE
  628.  
  629. Other Tools
  630. ***********
  631.  
  632. The AmigaNCP package contains a few more programs which are meant for
  633. the advanced user.  Since they are also good examples for how to access
  634. the amigancp.library, the source code for most of these utilities can
  635. be found in the Developer/Source/ drawer.
  636.  
  637. AmigaNCP-Monitor
  638. ================
  639.  
  640. The AmigaNCP-Monitor is a utility for monitoring the current network
  641. activity.  It displays an overview over the eight avaible NCP channels,
  642. their users, current connection states and the amount of data that has
  643. been transferred.
  644.  
  645.     AmigaNCP-Monitor may be started either from the shell or from
  646. Workbench.  There are no additional parameters.  The window position
  647. will be saved as a tooltype entry.
  648.  
  649. The Monitor opens a single window on the workbench screen.  The top
  650. part displays the states of the eight network channels, the bottom part
  651. shows overall statistics and whether NCP is currently connected.
  652.  
  653. ThisProc
  654.      The network name of the Amiga process using the channel.  The
  655.      first channel is always allocated by the LINK application.
  656.  
  657. RemotePr
  658.      The name of the remote process.  This may be empty, meaning the
  659.      channel is currently not connected.
  660.  
  661.          UnknClnt identifies a passive channel connected to an
  662.      unknown client.
  663.  
  664.      For the first channel, this may be either ARemLink, denoting
  665.      that the current connection has been initiated by the remote link,
  666.      or PRemLink, if the current connection was opened on behalf of
  667.      the amigancp.library.
  668.  
  669. Status
  670.      This flag array denotes various internal states of
  671.      amigancp.library.
  672.  
  673. Bytes Sent
  674.      How many bytes have been sent through this channel?
  675.  
  676. Bytes Received
  677.      How many bytes have been received through this channel?
  678.  
  679. Online since
  680.      The time on which amigancp.library was started first.  The
  681.      startup time is used by the NCP protocol to determine whether a
  682.      broken connection can be reestablished or not.
  683.  
  684. Remote NCP
  685.      The remote NCP's startup time.
  686.  
  687. Version
  688.      The remote NCP's version.  This is generally 2 for AmigaNCP and
  689.      the Psion S3 and 3 for the S3a.
  690.  
  691. Connected
  692.      This will be displayed whenever there is an active connection to
  693.      any remote NCP.
  694.  
  695. S3PrintServer
  696. =============
  697.  
  698. The S3PrintServer is a small utility which allows you to print from
  699. your Psion directly to a printer connected to the Amiga.  It uses the
  700. Psion's capability to print to a serial printer, and simply passes any
  701. data from the serial port directly to the printer device via raw writes.
  702.  
  703. You have to turn off the Remote Link on the Psion side and terminate
  704. any NCP application running on the Amiga side before starting the
  705. S3PrintServer.  If you forget to turn off the Remote Link, junk will
  706. be printed due to misinterpreted NCP packets!
  707.  
  708. You must also set your Psion's printer configuration to serial
  709. printing, with the same baud rate used for NCP connections, turn off
  710. Xon/Xoff and turn on RTS/CTS and DSR/DTR handshaking.  The
  711. S3PrintServer itself reads the serial configuration from the file
  712. ENV:NCP.config.
  713.  
  714. The S3PrintServer uses the raw write capabilities of the
  715. printer.device and therefore ignores any printer driver settings.
  716. However, it respects your choice on which device to print, and even
  717. allows printing via network printer services, e.g.  Envoy Network
  718. Printing.
  719.  
  720. Therefore, you must select the correct WDR printer driver on the
  721. Psion.  This can be done in the Printer Setup dialog of the
  722. Word application.
  723.  
  724. Having done all this, you can print from your Psion applications simply
  725. by selecting the Print... menu, just as if the printer was connected
  726. directly to the Psion.
  727.  
  728. S3Run
  729. =====
  730.  
  731. The S3Run utility uses the LINK application's capability to launch
  732. a process on the remote side.  It's a shell only program which takes
  733. one or two parameters: S3Run filename commandline
  734.  
  735. The first argument denotes the file name of the remote program to run,
  736. for example TEST.IMG.  Due to NCP restrictions, this may only be a
  737. program on the Psion's top level directory or ROM.
  738.  
  739. The second argument may contain the command line to be passed to the
  740. created process.  This argument may be omitted, in which case no command
  741. line will be passed.
  742.  
  743. You may use \xx escaping to insert the hexadecimal code xx into
  744. the command line.  See `the Psion SIBO SDK Manual' for more information
  745. on S3 command lines.
  746.  
  747. API
  748. ***
  749.  
  750. This part of the AmigaNCP documentation describes the use of AmigaNCP
  751. services within custom applications.  It assumes a broad knowledge of
  752. programming AmigaOS.
  753.  
  754. NCP Implementation
  755. ==================
  756.  
  757. The Psion NCP network protocol consists of four layers:
  758.  
  759. Serial Layer
  760.      A simple asynchronous serial 8/N/1 connection.  This is in fact
  761.      the hardware serial connection built into the 3-Link.
  762.  
  763. Packet Layer
  764.      A packet protocol providing checksums and multiple
  765.      retransmissions.  It is called LLMAC and somewhat based on the
  766.      MNP type protocols.
  767.  
  768. NCP Layer
  769.      NCP provides up to eight independant data streams between local
  770.      and remote processes.  Under the Psion OS, a process may use only
  771.      one NCP channel at a time.
  772.  
  773. Application Layer
  774.      Applications built on top of the NCP data stream service.  This
  775.      includes the remote file system and remote file server.  There is
  776.      also a supervisory application called LINK which controls the
  777.      server setup.
  778.  
  779. A more detailed description of NCP usage from the Psion side can be
  780. found in the `Psion SIBO SDK Manual, I/O Devices Reference'.
  781.  
  782. On the Amiga side, the serial layer is provided through any standard
  783. EXEC serial device, normally this will be the internal port's
  784. serial.device.  The packet and NCP layers have been built into
  785. the amigancp.library.
  786.  
  787. Besides these basic layers, also the supervisory LINK application
  788. resides in the
  789.     amigancp.library.
  790.  
  791. All network services are accessible via function calls to the
  792. amigancp.library.  In order to use these functions, you have to
  793. open the amigancp.library first:
  794.  
  795.          #include <libraries/ncp.h>
  796.      
  797.          struct Library *NCPBase;
  798.          NCPBase = OpenLibrary( "amigancp.library", NCP_VERSION );
  799.          if( !NCPBase )
  800.              fail_app();
  801.  
  802. If you use SAS/C 6.50 or above, you may want to use the link library
  803. ncp.lib provided in the development toolkit.  It contains a
  804. constructor/destructor pair that automatically opens/closes the
  805. amigancp.library upon startup/termination of your application.
  806.  
  807. If you are not using C, you'll have to build your own language specific
  808. glue definitions.  A function description file
  809. (Developer/FD/ncp_lib.fd) has been included.  The AmigaNCP
  810. programming interface doesn't use any fancy data structures, so you
  811. should have no problems with other programming languages.
  812.  
  813. The NCP network services are based on channels.  A channel is a
  814. connection between a local and a remote processes.  In the Psion EPOC
  815. environment, a channel is bound to a single process and bears the name
  816. of that process.  AmigaNCP allows you to specify arbitrary names for
  817. your channels, along with having multiple channels within a single
  818. application, if you wish to do so.
  819.  
  820. A channel may be opened in either active or passive mode.  An
  821. active channel attempts to connect to a remote process with a given name
  822. and refuses to open if the remote process doesn't exists or already is
  823. busy with some other connection.  A passive channel just sits around
  824. awaiting a connection from the remote site.  Passive channels are
  825. normally used for server applications awaiting connections from their
  826. clients, whereas active channels are used by clients to contact their
  827. server application.
  828.  
  829. I/O via NCP is done either synchronously or asynchronously.  The
  830. I/O interface of the amigancp.library is quite similar to the EXEC
  831. device I/O interface.  See the function descriptions of the NCP I/O
  832. functions for more details.
  833.  
  834. The Developer/Source/ drawer provides some examples to show the use
  835. of the
  836.     amigancp.library calls.
  837.  
  838. Function Reference
  839. ==================
  840.  
  841. Note that this function reference is also available in standard Amiga
  842. Autodoc format (Developer/Autodocs/ncp.doc).
  843.  
  844. The amigancp.library also contains a clone set of the exec.library
  845. memory pool functions which do work with AmigaOS 2.x systems. The the
  846. exec.library documentation for more information about these functions.
  847.  
  848. NCP_CloseChannel
  849. ----------------
  850.  
  851.         NAME
  852.          NCP_CloseChannel -- close an NCP channel
  853.      
  854.         SYNOPSIS
  855.          NCP_CloseChannel( channel )
  856.                             A0
  857.      
  858.         void NCP_CloseChannel( APTR );
  859.      
  860.         FUNCTION
  861.          Close a NCP channel previously opened by NCP_OpenChannel().
  862.          If this is an active link to the remote machine, it will be
  863.          closed.
  864.      
  865.         INPUTS
  866.          channel -- channel to close. May be NULL, in which case
  867.                     this functions does nothing.
  868.      
  869.         RESULT
  870.          None.
  871.      
  872.         EXAMPLE
  873.      
  874.         NOTES
  875.          An active NCP connection will be dropped about 10s
  876.          after the last channel has been closed.
  877.      
  878.         BUGS
  879.          None known.
  880.      
  881.         SEE ALSO
  882.          NCP_OpenChannel()
  883.  
  884. NCP_OpenChannel
  885. ---------------
  886.  
  887.         NAME
  888.          NCP_OpenChannel -- open an NCP channel to attempt to connect to
  889.                            the remote.
  890.      
  891.         SYNOPSIS
  892.          channel = NCP_OpenChannel( localname, remotename, flags )
  893.            D0                          A0          A1        D0
  894.      
  895.          APTR NCP_OpenChannel( STRPTR, STRPTR, ULONG );
  896.      
  897.         FUNCTION
  898.          Opens an NCP channel. If remotename is not NULL, attempts
  899.          to connect to the remote process and fails with a NULL
  900.          return if the connection could not be made. If remotename
  901.          is NULL, creates a passive channel silently awaiting remote
  902.          connection.
  903.      
  904.         INPUTS
  905.          localname -- name of local "process"
  906.          remotename -- either NULL for a passive channel or
  907.                        the remote process name which to connect
  908.                        to
  909.          flags -- currently unused, leave at 0
  910.      
  911.         RESULT
  912.          channel -- pointer to a channel object. NULL in case of
  913.                     an error, whereas additional error information
  914.                     can be found in IoErr()
  915.      
  916.         EXAMPLE
  917.          To connect to the remote file server:
  918.      
  919.             APTR channel;
  920.             channel = NCP_OpenChannel( "TestHost", "SYS$RFSV.*", 0 );
  921.      
  922.      
  923.         NOTES
  924.          Opening an active channel will result in an attempt to
  925.          create an NCP connection and fail upon any error (including
  926.          serial failure or inexistance of the remote process).
  927.          Creating an passive channel will not cause an NCP connection
  928.          attempt; this is done upon the first I/O request made to
  929.          channel.
  930.      
  931.         BUGS
  932.          None known.
  933.      
  934.         SEE ALSO
  935.          NCP_CloseChannel()
  936.  
  937. NCP_Read
  938. --------
  939.  
  940.         NAME
  941.          NCP_Read -- do a read request.
  942.      
  943.         SYNOPSIS
  944.          status = NCP_Read( channel, data, datasize )
  945.            D0                     A0
  946.      
  947.          LONG NCP_Read( APTR, APTR, ULONG );
  948.      
  949.         FUNCTION
  950.          This is basically identical to calling NCP_BeginRead()
  951.          followed by NCP_WaitRead().
  952.      
  953.         INPUTS
  954.          channel -- a NCP channel created by NCP_OpenChannel()
  955.          data -- receive buffer
  956.          datasize -- receive buffer size
  957.      
  958.         RESULT
  959.          status -- number of bytes read or a negative error
  960.                    number.
  961.      
  962.         EXAMPLE
  963.      
  964.         NOTES
  965.      
  966.         BUGS
  967.      
  968.         SEE ALSO
  969.          NCP_WaitRead(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead()
  970.  
  971. NCP_BeginRead
  972. -------------
  973.  
  974.         NAME
  975.          NCP_BeginRead -- start a read request on the NCP channel.
  976.      
  977.         SYNOPSIS
  978.          error = NCP_BeginRead( channel, data, datasize )
  979.            D0                     A0      A1       D0
  980.      
  981.          LONG NCP_BeginRead( APTR, APTR, ULON G);
  982.      
  983.         FUNCTION
  984.          Queues a read operation on the current NCP channel.
  985.      
  986.         INPUTS
  987.          channel -- a NCP channel created by NCP_OpenChannel()
  988.          data -- receive buffer
  989.          datasize -- receive buffer size
  990.      
  991.         RESULT
  992.          error -- either 0 if the read was queued successfully
  993.                   or a negative error number
  994.      
  995.         EXAMPLE
  996.      
  997.         NOTES
  998.          Only one read request may be queued at a time on a single
  999.          channel. This function fails with NCPE_INUSE if there is
  1000.          already a read request outstanding.
  1001.      
  1002.         BUGS
  1003.          None known.
  1004.      
  1005.         SEE ALSO
  1006.          NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_CheckRead()
  1007.  
  1008. NCP_AbortRead
  1009. -------------
  1010.  
  1011.         NAME
  1012.          NCP_AbortRead -- abort read currently in progress
  1013.      
  1014.         SYNOPSIS
  1015.          NCP_AbortRead( channel )
  1016.                           A0
  1017.      
  1018.          void NCP_AbortRead( APTR )
  1019.      
  1020.         FUNCTION
  1021.          Aborts the current read request on the given NCP channel.
  1022.          Does nothing if no read is pending.
  1023.      
  1024.         INPUTS
  1025.          channel -- a NCP channel created by NCP_OpenChannel()
  1026.      
  1027.         RESULT
  1028.          None.
  1029.      
  1030.         EXAMPLE
  1031.      
  1032.         NOTES
  1033.          Never forget to finish a read request using NCP_WaitRead(),
  1034.          or you'll end up in OS hell.
  1035.      
  1036.         BUGS
  1037.          None known.
  1038.      
  1039.         SEE ALSO
  1040.          NCP_Read(), NCP_WaitRead(), NCP_CheckRead(), NCP_BeginRead()
  1041.  
  1042. NCP_CheckRead
  1043. -------------
  1044.  
  1045.         NAME
  1046.          NCP_CheckRead -- check if a read request is still pending
  1047.      
  1048.         SYNOPSIS
  1049.          status = NCP_CheckRead( channel )
  1050.            D0                       A0
  1051.      
  1052.          LONG NCP_CheckRead( APTR )
  1053.      
  1054.         FUNCTION
  1055.          Check if a read request is still pending on the given NCP
  1056.          channel.
  1057.      
  1058.         INPUTS
  1059.          channel -- a NCP channel created by NCP_OpenChannel()
  1060.      
  1061.         RESULT
  1062.          status -- FALSE if a read is currently pending,
  1063.                    TRUE if no request is pending or the current
  1064.                    request has completed.
  1065.      
  1066.         EXAMPLE
  1067.      
  1068.         NOTES
  1069.          Never forget to finish a read request using NCP_WaitRead(),
  1070.          or you'll end up in OS hell.
  1071.      
  1072.         BUGS
  1073.          None known.
  1074.      
  1075.         SEE ALSO
  1076.          NCP_Read(), NCP_WaitRead(), NCP_AbortRead(), NCP_BeginRead()
  1077.  
  1078. NCP_WaitRead
  1079. ------------
  1080.  
  1081.         NAME
  1082.          NCP_WaitRead -- complete a read request on the NCP channel.
  1083.      
  1084.         SYNOPSIS
  1085.          result = NCP_WaitRead( channel )
  1086.            D0                     A0
  1087.      
  1088.          LONG NCP_WaitRead( APTR );
  1089.      
  1090.         FUNCTION
  1091.          Waits for the current read request to finish and
  1092.          returns the result.
  1093.      
  1094.         INPUTS
  1095.          channel -- a NCP channel created by NCP_OpenChannel()
  1096.      
  1097.         RESULT
  1098.          status -- number of bytes read or a negative error
  1099.                    number.
  1100.      
  1101.         EXAMPLE
  1102.      
  1103.         NOTES
  1104.          Every read request startet with NCP_BeginRead() absolutely
  1105.          must be followed by a NCP_WaitRead(), even if it already
  1106.          finished or was aborted via NCP_AbortRead().
  1107.      
  1108.         BUGS
  1109.          Calling this function without an queued read request
  1110.          will hang up your process.
  1111.      
  1112.         SEE ALSO
  1113.          NCP_Read(), NCP_BeginRead(), NCP_AbortRead(), NCP_CheckRead()
  1114.  
  1115. NCP_ReadSig
  1116. -----------
  1117.  
  1118.         NAME
  1119.          NCP_ReadSig -- return signal mask of channel read port.
  1120.      
  1121.         SYNOPSIS
  1122.          sigmask = NCP_ReadSig( channel )
  1123.            D0                     A0
  1124.      
  1125.          ULONG NCP_ReadSig( APTR );
  1126.      
  1127.         FUNCTION
  1128.          This function returns the signal mask of the read port
  1129.          of the given NCP channel. This signal is set if a read
  1130.          request completes.
  1131.      
  1132.         INPUTS
  1133.          channel -- a NCP channel created by NCP_OpenChannel()
  1134.      
  1135.         RESULT
  1136.          sigmask -- signal mask of read port.
  1137.      
  1138.         EXAMPLE
  1139.      
  1140.         NOTES
  1141.          Note that this function returns a signal mask, not a signal bit number.
  1142.      
  1143.         BUGS
  1144.      
  1145.         SEE ALSO
  1146.          NCP_BeginRead()
  1147.  
  1148. NCP_Write
  1149. ---------
  1150.  
  1151.         NAME
  1152.          NCP_Write -- do a write request.
  1153.      
  1154.         SYNOPSIS
  1155.          status = NCP_Write( channel, data, datasize )
  1156.            D0                   A0     A1      D0
  1157.      
  1158.          LONG NCP_Write( APTR, APTR, ULONG );
  1159.      
  1160.         FUNCTION
  1161.          This is basically identical to calling NCP_BeginWrite()
  1162.          followed by NCP_WaitWrite().
  1163.      
  1164.         INPUTS
  1165.          channel -- a NCP channel created by NCP_OpenChannel()
  1166.          data -- receive buffer
  1167.          datasize -- receive buffer size
  1168.      
  1169.         RESULT
  1170.          status -- number of bytes written or a negative error
  1171.                    number.
  1172.      
  1173.         EXAMPLE
  1174.      
  1175.         NOTES
  1176.      
  1177.         BUGS
  1178.      
  1179.         SEE ALSO
  1180.          NCP_WaitWrite(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite()
  1181.  
  1182. NCP_BeginWrite
  1183. --------------
  1184.  
  1185.         NAME
  1186.          NCP_BeginWrite -- start a write request on the NCP channel.
  1187.      
  1188.         SYNOPSIS
  1189.          error = NCP_BeginWrite( channel, data, datasize )
  1190.            D0                     A0      A1       D0
  1191.      
  1192.          LONG NCP_BeginWrite( APTR, APTR, ULON G);
  1193.      
  1194.         FUNCTION
  1195.          Queues a write operation on the current NCP channel.
  1196.      
  1197.         INPUTS
  1198.          channel -- a NCP channel created by NCP_OpenChannel()
  1199.          data -- data buffer
  1200.          datasize -- data buffer size
  1201.      
  1202.         RESULT
  1203.          error -- either 0 if the write was queued successfully
  1204.                   or a negative error number
  1205.      
  1206.         EXAMPLE
  1207.      
  1208.         NOTES
  1209.          Only one write request may be queued at a time on a single
  1210.          channel. This function fails with NCPE_INUSE if there is
  1211.          already a write request outstanding.
  1212.      
  1213.         BUGS
  1214.          None known.
  1215.      
  1216.         SEE ALSO
  1217.          NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_CheckWrite()
  1218.  
  1219. NCP_AbortWrite
  1220. --------------
  1221.  
  1222.         NAME
  1223.          NCP_AbortWrite -- abort write currently in progress
  1224.      
  1225.         SYNOPSIS
  1226.          NCP_AbortWrite( channel )
  1227.                           A0
  1228.      
  1229.          void NCP_AbortWrite( APTR )
  1230.      
  1231.         FUNCTION
  1232.          Aborts the current write request on the given NCP channel.
  1233.          Does nothing if no write is pending.
  1234.      
  1235.         INPUTS
  1236.          channel -- a NCP channel created by NCP_OpenChannel()
  1237.      
  1238.         RESULT
  1239.          None.
  1240.      
  1241.         EXAMPLE
  1242.      
  1243.         NOTES
  1244.          Never forget to finish a write request using NCP_WaitWrite(),
  1245.          or you'll end up in OS hell.
  1246.      
  1247.         BUGS
  1248.          None known.
  1249.      
  1250.         SEE ALSO
  1251.          NCP_Write(), NCP_WaitWrite(), NCP_CheckWrite(), NCP_BeginWrite()
  1252.  
  1253. NCP_CheckWrite
  1254. --------------
  1255.  
  1256.         NAME
  1257.          NCP_CheckWrite -- check if a write request is still pending
  1258.      
  1259.         SYNOPSIS
  1260.          status = NCP_CheckWrite( channel )
  1261.            D0                       A0
  1262.      
  1263.          LONG NCP_CheckWrite( APTR )
  1264.      
  1265.         FUNCTION
  1266.          Check if a write request is still pending on the given NCP
  1267.          channel.
  1268.      
  1269.         INPUTS
  1270.          channel -- a NCP channel created by NCP_OpenChannel()
  1271.      
  1272.         RESULT
  1273.          status -- FALSE if a write is currently pending,
  1274.                    TRUE if no request is pending or the current
  1275.                    request has completed.
  1276.      
  1277.         EXAMPLE
  1278.      
  1279.         NOTES
  1280.          Never forget to finish a write request using NCP_WaitWrite(),
  1281.          or you'll end up in OS hell.
  1282.      
  1283.         BUGS
  1284.          None known.
  1285.      
  1286.         SEE ALSO
  1287.          NCP_Write(), NCP_WaitWrite(), NCP_AbortWrite(), NCP_BeginWrite()
  1288.  
  1289. NCP_WaitWrite
  1290. -------------
  1291.  
  1292.         NAME
  1293.          NCP_WaitWrite -- complete a write request on the NCP channel.
  1294.      
  1295.         SYNOPSIS
  1296.          result = NCP_WaitWrite( channel )
  1297.            D0                     A0
  1298.      
  1299.          LONG NCP_WaitWrite( APTR );
  1300.      
  1301.         FUNCTION
  1302.          Waits for the current write request to finish and
  1303.          returns the result.
  1304.      
  1305.         INPUTS
  1306.          channel -- a NCP channel created by NCP_OpenChannel()
  1307.      
  1308.         RESULT
  1309.          status -- number of bytes written or a negative error
  1310.                    number.
  1311.      
  1312.         EXAMPLE
  1313.      
  1314.         NOTES
  1315.          Every write request startet with NCP_BeginWrite() absolutely
  1316.          must be followed by a NCP_WaitWrite(), even if it already
  1317.          finished or was aborted via NCP_AbortWrite().
  1318.      
  1319.         BUGS
  1320.          Calling this function without an queued write request
  1321.          will hang up your process.
  1322.      
  1323.         SEE ALSO
  1324.          NCP_Write(), NCP_BeginWrite(), NCP_AbortWrite(), NCP_CheckWrite()
  1325.  
  1326. NCP_WriteSig
  1327. ------------
  1328.  
  1329.         NAME
  1330.          NCP_WriteSig -- return signal mask of channel write port.
  1331.      
  1332.         SYNOPSIS
  1333.          sigmask = NCP_WriteSig( channel )
  1334.            D0                     A0
  1335.      
  1336.          ULONG NCP_WriteSig( APTR );
  1337.      
  1338.         FUNCTION
  1339.          This function returns the signal mask of the write port
  1340.          of the given NCP channel. This signal is set if a write
  1341.          request completes.
  1342.      
  1343.         INPUTS
  1344.          channel -- a NCP channel created by NCP_OpenChannel()
  1345.      
  1346.         RESULT
  1347.          sigmask -- signal mask of write port.
  1348.      
  1349.         EXAMPLE
  1350.      
  1351.         NOTES
  1352.          Note that this function returns a signal mask, not a signal bit number.
  1353.      
  1354.         BUGS
  1355.      
  1356.         SEE ALSO
  1357.          NCP_BeginWrite()
  1358.  
  1359. NCP_Fault
  1360. ---------
  1361.  
  1362.         NAME
  1363.          NCP_Fault -- return localized NCP error string
  1364.      
  1365.         SYNOPSIS
  1366.          NCP_Fault( code, header, buffer, buffersize );
  1367.                     D0     A0      A1        D1
  1368.      
  1369.         void NCP_Fault( LONG, STRPTR, STRPTR, ULONG );
  1370.      
  1371.         FUNCTION
  1372.          Returns a localized text string associated with the
  1373.          error code.
  1374.      
  1375.         INPUTS
  1376.          code -- NCP error code
  1377.          header -- header to insert before string. May be NULL
  1378.          buffer -- buffer to write the error text to
  1379.          buffersize -- size of buffer
  1380.      
  1381.         RESULT
  1382.          None.
  1383.      
  1384.         EXAMPLE
  1385.      
  1386.         NOTES
  1387.      
  1388.         BUGS
  1389.          None known.
  1390.      
  1391.         SEE ALSO
  1392.          dos.library/Fault()
  1393.  
  1394. NCP_LinkRemoteRun
  1395. -----------------
  1396.  
  1397.         NAME
  1398.          NCP_LinkRemoteRun -- use the NCP link channel to run a program on
  1399.                               the remote machine.
  1400.      
  1401.         SYNOPSIS
  1402.          error = NCP_LinkRemoteRun( filename, cmdline, cmdlinelen )
  1403.          D0                            A0       A1        D0
  1404.      
  1405.         LONG NCP_LinkRemoteRun( STRPTR, APTR, ULONG );
  1406.      
  1407.         FUNCTION
  1408.          Use the LINK supervisor channel to have the remote link
  1409.          run a program. No NCP channel needs to be opened in order
  1410.          to perform this operation.
  1411.      
  1412.         INPUTS
  1413.          filename -- file name of the remote program to start
  1414.          cmdline -- pointer to command line array. Note that
  1415.                     EPOC command lines are *NOT* zero terminated.
  1416.          cmdlinelen -- length of command line in bytes. May be
  1417.                        zero, in which case no command line
  1418.                        is transfered.
  1419.      
  1420.         RESULT
  1421.          error -- either an AmigaNCP specific error code or the
  1422.                   result code from the remote link.
  1423.      
  1424.         EXAMPLE
  1425.          Have WORD.APP read the Amiga startup sequence:
  1426.      
  1427.             UBYTE cmdline[] = {
  1428.              "OANCPTest\000 V TES\000REM::SYS:\S\STARTUP-SEQUENCE\000"
  1429.             };
  1430.             error = NCP_LinkRemoteRun( "WORD.APP", cmdline, sizeof( cmdline ) );
  1431.      
  1432.         NOTES
  1433.          See the Psion SDK for more information about using commandlines and
  1434.          the LINK process launch feature.
  1435.      
  1436.         BUGS
  1437.          None known.
  1438.      
  1439.         SEE ALSO
  1440.  
  1441. NCP_clnl
  1442. --------
  1443.  
  1444.         NAME
  1445.          NCP_clnl -- clear CR/LF at end of line.
  1446.      
  1447.         SYNOPSIS
  1448.          NCP_clnl( string )
  1449.                    A0
  1450.      
  1451.          void NCP_clnl( STRPTR );
  1452.      
  1453.         FUNCTION
  1454.          Clears any CR or LF characters at the end of the string.
  1455.      
  1456.         INPUTS
  1457.          string -- pointer to string (contents will be modified)
  1458.      
  1459.         RESULT
  1460.          None.
  1461.      
  1462.         EXAMPLE
  1463.      
  1464.         NOTES
  1465.      
  1466.         BUGS
  1467.          None known.
  1468.      
  1469.         SEE ALSO
  1470.  
  1471. NCP_ibm2iso
  1472. -----------
  1473.  
  1474.         NAME
  1475.          NCP_ibm2iso -- convert IBM to ISO charachter
  1476.      
  1477.         SYNOPSIS
  1478.          isochar = NCP_ibm2iso( ibmchar )
  1479.            D0                    D0 0:7
  1480.      
  1481.          UBYTE NCP_ibm2iso( UBYTE );
  1482.      
  1483.         FUNCTION
  1484.          Converts a character from the IBM to the ISO charset.
  1485.      
  1486.         INPUTS
  1487.          ibmchar -- character of the IBM codeset
  1488.      
  1489.         RESULT
  1490.          isochar -- equivalent character in the ISO codeset
  1491.      
  1492.         EXAMPLE
  1493.      
  1494.         NOTES
  1495.      
  1496.         BUGS
  1497.          None known.
  1498.      
  1499.         SEE ALSO
  1500.  
  1501. NCP_tab_ibm2iso
  1502. ---------------
  1503.  
  1504.         NAME
  1505.          NCP_tab_ibm2iso -- returns pointer to internal ibm2iso tab
  1506.      
  1507.         SYNOPSIS
  1508.          tab = NCP_tab_ibm2iso()
  1509.          D0/A0
  1510.      
  1511.          UBYTE *NCP_tab_ibm2iso( void );
  1512.      
  1513.         FUNCTION
  1514.          Returns a pointer to the internal ibm2iso conversion table.
  1515.          This allows you to do more efficient conversion.
  1516.      
  1517.         INPUTS
  1518.          None.
  1519.      
  1520.         RESULT
  1521.          tab -- pointer to 256 byte conversion table.
  1522.      
  1523.         EXAMPLE
  1524.      
  1525.         NOTES
  1526.          The pointer is returned both in D0 and A0.
  1527.      
  1528.         BUGS
  1529.          None known.
  1530.      
  1531.         SEE ALSO
  1532.  
  1533. NCP_tab_iso2ibm
  1534. ---------------
  1535.  
  1536.         NAME
  1537.          NCP_tab_iso2ibm -- returns pointer to internal iso2ibm tab
  1538.      
  1539.         SYNOPSIS
  1540.          tab = NCP_tab_iso2ibm()
  1541.          D0/A0
  1542.      
  1543.          UBYTE *NCP_tab_iso2ibm( void );
  1544.      
  1545.         FUNCTION
  1546.          Returns a pointer to the internal ISO2IBM conversion table.
  1547.          This allows you to do more efficient conversion.
  1548.      
  1549.         INPUTS
  1550.          None.
  1551.      
  1552.         RESULT
  1553.          tab -- pointer to 256 byte conversion table.
  1554.      
  1555.         EXAMPLE
  1556.      
  1557.         NOTES
  1558.          The pointer is returned both in D0 and A0.
  1559.      
  1560.         BUGS
  1561.          None known.
  1562.      
  1563.         SEE ALSO
  1564.  
  1565. NCP_iso2ibm
  1566. -----------
  1567.  
  1568.         NAME
  1569.          NCP_iso2ibm -- convert IBM to ISO charachter
  1570.      
  1571.         SYNOPSIS
  1572.          ibmchar = NCP_iso2ibm( isochar )
  1573.            D0                    D0 0:7
  1574.      
  1575.          UBYTE NCP_iso2ibm( UBYTE );
  1576.      
  1577.         FUNCTION
  1578.          Converts a character from the ISO to the IBM charset.
  1579.      
  1580.         INPUTS
  1581.          isochar -- character of the ISO codeset
  1582.      
  1583.         RESULT
  1584.          ibmchar -- equivalent character in the IBM codeset
  1585.      
  1586.         EXAMPLE
  1587.      
  1588.         NOTES
  1589.      
  1590.         BUGS
  1591.          None known.
  1592.      
  1593.         SEE ALSO
  1594.  
  1595. NCP_IWORD
  1596. ---------
  1597.  
  1598.         NAME
  1599.          NCP_IWORD -- swap bytes in word
  1600.      
  1601.         SYNOPSIS
  1602.          sword = NCP_IWORD( word )
  1603.            D0                D0
  1604.      
  1605.          UWORD NCP_IWORD( UWORD );
  1606.      
  1607.         FUNCTION
  1608.          Swaps the byte order within the word.
  1609.      
  1610.         INPUTS
  1611.          word -- a 16 bit data word.
  1612.      
  1613.         RESULT
  1614.          sword -- the same word with the byte order swapped.
  1615.      
  1616.         EXAMPLE
  1617.      
  1618.         NOTES
  1619.      
  1620.         BUGS
  1621.          None known.
  1622.      
  1623.         SEE ALSO
  1624.  
  1625. NCP_IWORDP
  1626. ----------
  1627.  
  1628.         NAME
  1629.          NCP_IWORDP -- swap bytes in word (pointer version)
  1630.      
  1631.         SYNOPSIS
  1632.          sword = NCP_IWORDP( wordp1, wordp2 )
  1633.            D0                  A0      A1
  1634.      
  1635.          UWORD NCP_IWORDP( UWORD *, UWORD * );
  1636.      
  1637.         FUNCTION
  1638.          Swaps the byte order from the word pointed to by wordp1
  1639.          and places the result in the word pointed to by wordp2.
  1640.      
  1641.         INPUTS
  1642.          wordp1 -- pointer to source word
  1643.          wordp2 -- pointer to destination word
  1644.      
  1645.         RESULT
  1646.          sword -- the same word with the byte order swapped.
  1647.      
  1648.         EXAMPLE
  1649.      
  1650.         NOTES
  1651.          The words don't need to be word aligned.
  1652.      
  1653.         BUGS
  1654.          The 68020++ version of amigancp.library requires the hardware
  1655.          to be able to do misaligned word accesses. Some early
  1656.          accelerator boards may have problems doing this.
  1657.      
  1658.         SEE ALSO
  1659.  
  1660. NCP_IWORDPI
  1661. -----------
  1662.  
  1663.         NAME
  1664.          NCP_IWORDPI -- swap bytes in word (in-place pointer version)
  1665.      
  1666.         SYNOPSIS
  1667.          sword = NCP_IWORDPI( wordp1 )
  1668.            D0                   A0
  1669.      
  1670.          UWORD NCP_IWORDP( UWORD * )
  1671.      
  1672.         FUNCTION
  1673.          Swaps the byte order within the word pointed to by wordp.
  1674.      
  1675.         INPUTS
  1676.          wordp -- pointer to word to swap
  1677.      
  1678.         RESULT
  1679.          sword -- the same word with the byte order swapped.
  1680.      
  1681.         EXAMPLE
  1682.      
  1683.         NOTES
  1684.          The word doesn't need to be word aligned.
  1685.      
  1686.         BUGS
  1687.          The 68020++ version of amigancp.library requires the hardware
  1688.          to be able to do misaligned word accesses. Some early
  1689.          accelerator boards may have problems doing this.
  1690.      
  1691.         SEE ALSO
  1692.  
  1693. NCP_ILONG
  1694. ---------
  1695.  
  1696.         NAME
  1697.          NCP_ILONG -- swap bytes in longword
  1698.      
  1699.         SYNOPSIS
  1700.          slongword = NCP_ILONG( longword )
  1701.            D0                     D0
  1702.      
  1703.          ULONG NCP_ILONG( ULONG );
  1704.      
  1705.         FUNCTION
  1706.          Swaps the byte order within the longword.
  1707.      
  1708.         INPUTS
  1709.          longword -- a 32 bit data word.
  1710.      
  1711.         RESULT
  1712.          slongword -- the same word with the byte order swapped.
  1713.      
  1714.         EXAMPLE
  1715.      
  1716.         NOTES
  1717.      
  1718.         BUGS
  1719.          None known.
  1720.      
  1721.         SEE ALSO
  1722.  
  1723. NCP_ILONGP
  1724. ----------
  1725.  
  1726.         NAME
  1727.          NCP_ILONGP -- swap bytes in longword (pointer version)
  1728.      
  1729.         SYNOPSIS
  1730.          sword = NCP_ILONGP( longwordp1, longwordp2 )
  1731.            D0                    A0          A1
  1732.      
  1733.          ULONG NCP_ILONGP( ULONG *, ULONG * );
  1734.      
  1735.         FUNCTION
  1736.          Swaps the byte order from the longword pointed to by longwordp1
  1737.          and places the result in the longword pointed to by longwordp2.
  1738.      
  1739.         INPUTS
  1740.          longwordp1 -- pointer to source longword
  1741.          longwordp2 -- pointer to destination longword
  1742.      
  1743.         RESULT
  1744.          sword -- the same word with the byte order swapped.
  1745.      
  1746.         EXAMPLE
  1747.      
  1748.         NOTES
  1749.          The longwords don't need to be word aligned.
  1750.      
  1751.         BUGS
  1752.          The 68020++ version of amigancp.library requires the hardware
  1753.          to be able to do misaligned word accesses. Some early
  1754.          accelerator boards may have problems doing this.
  1755.      
  1756.         SEE ALSO
  1757.  
  1758. NCP_ILONGPI
  1759. -----------
  1760.  
  1761.         NAME
  1762.          NCP_ILONGPI -- swap bytes in longword (in-place pointer version)
  1763.      
  1764.         SYNOPSIS
  1765.          sword = NCP_ILONGPI( longwordp )
  1766.            D0                    A0
  1767.      
  1768.          ULONG NCP_ILONGP( ULONG * )
  1769.      
  1770.         FUNCTION
  1771.          Swaps the byte order within the longword pointed to by longwordp.
  1772.      
  1773.         INPUTS
  1774.          longwordp -- pointer to longword to swap
  1775.      
  1776.         RESULT
  1777.          sword -- the same word with the byte order swapped.
  1778.      
  1779.         EXAMPLE
  1780.      
  1781.         NOTES
  1782.          The longword doesn't need to be word aligned.
  1783.      
  1784.         BUGS
  1785.          The 68020++ version of amigancp.library requires the hardware
  1786.          to be able to do misaligned word accesses. Some early
  1787.          accelerator boards may have problems doing this.
  1788.      
  1789.         SEE ALSO
  1790.  
  1791. Error codes from NCP functions
  1792. ==============================
  1793.  
  1794. Several amigancp.library functions may return negative error
  1795. numbers.  Note that besides the errors internal to
  1796. amigancp.library, standard EPOC OS errors may be returned by some
  1797. functions.
  1798.  
  1799. NCPE_INUSE (-1)
  1800.      There is already a read/write request pending on the given channel.
  1801.  
  1802. NCPE_ABORTED (-2)
  1803.      The read/write request has been aborted by NCP_AbortXXX()
  1804.  
  1805. NCPE_OFFLINE (-3)
  1806.      There is no NCP connection.  This may denote that the remote NCP
  1807.      closed the connection.
  1808.  
  1809. NCPE_INACTIVE (-4)
  1810.      The channel is currently inactive.  Most likely it has been closed
  1811.      by the remote process, or the NCP connection is currently dropped
  1812.      due to serial link failure.
  1813.  
  1814. NCPE_NOTFOUND (-5)
  1815.      You attempted to open an active channel and the remote process
  1816.      didn't exist.
  1817.  
  1818. NCPE_RECONNECTED (-6)
  1819.      This is not really an error.  Queued read requests will be
  1820.      terminated with this error value if the NCP connection has been
  1821.      succesfully reconnected.
  1822.  
  1823. NCPE_NEWUSER (-7)
  1824.      This is not really an error.  It may come up if the remote client
  1825.      of a passive channel changed.
  1826.  
  1827. Index
  1828. *****
  1829.  
  1830.  
  1831.  
  1832.  NCP.config                             Using AmigaNCP
  1833.  AmigaNCP File Server                   File Server
  1834.  AmigaNCP File System                   File System
  1835.  amigancp.library calls                 API
  1836.  amigancp.library functions             API
  1837.  API                                    API
  1838.  error codes                            Errors
  1839.  File Server options                    File Server
  1840.  File System Options                    File System
  1841.  function calls                         API
  1842.  Installation                           Using AmigaNCP
  1843.  Installing AmigaNCP                    Using AmigaNCP
  1844.  Introduction                           Introduction
  1845.  Monitor                                AmigaNCP-Monitor
  1846.  NCP errors                             Errors
  1847.  NCP-Monitor                            AmigaNCP-Monitor
  1848.  NCP_AbortRead                          NCP_AbortRead
  1849.  NCP_AbortWrite                         NCP_AbortWrite
  1850.  NCP_BeginRead                          NCP_BeginRead
  1851.  NCP_BeginWrite                         NCP_BeginWrite
  1852.  NCP_CheckRead                          NCP_CheckRead
  1853.  NCP_CheckWrite                         NCP_CheckWrite
  1854.  NCP_clnl                               NCP_clnl
  1855.  NCP_CloseChannel                       NCP_CloseChannel
  1856.  NCP_Fault                              NCP_Fault
  1857.  NCP_ibm2iso                            NCP_ibm2iso
  1858.  NCP_ILONG                              NCP_ILONG
  1859.  NCP_ILONGP                             NCP_ILONGP
  1860.  NCP_ILONGPI                            NCP_ILONGPI
  1861.  NCP_iso2ibm                            NCP_iso2ibm
  1862.  NCP_IWORD                              NCP_IWORD
  1863.  NCP_IWORDP                             NCP_IWORDP
  1864.  NCP_IWORDPI                            NCP_IWORDPI
  1865.  NCP_LinkRemoteRun                      NCP_LinkRemoteRun
  1866.  NCP_OpenChannel                        NCP_OpenChannel
  1867.  NCP_Read                               NCP_Read
  1868.  NCP_ReadSig                            NCP_ReadSig
  1869.  NCP_tab_ibm2iso                        NCP_tab_ibm2iso
  1870.  NCP_tab_iso2ibm                        NCP_tab_iso2ibm
  1871.  NCP_WaitRead                           NCP_WaitRead
  1872.  NCP_WaitWrite                          NCP_WaitWrite
  1873.  NCP_Write                              NCP_Write
  1874.  NCP_WriteSig                           NCP_WriteSig
  1875.  Network Monitor                        AmigaNCP-Monitor
  1876.  Options, File Server                   File Server
  1877.  Options, File System                   File System
  1878.  Other Tools                            Other Tools
  1879.  Parts                                  Introduction
  1880.  Remote File Server                     File Server
  1881.  Remote File System                     File System
  1882.  S3PrintServer                          S3PrintServer
  1883.  S3Run                                  S3Run
  1884.  serial configuration                   Using AmigaNCP
  1885.  serial.device, configuration of        Using AmigaNCP
  1886.  
  1887.